home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 1 Issue 2 / PDCD-1 - Issue 02.iso / _utilities / utilities / 003 / _unimode2 / !UniMode2 / Manuals / PRM < prev    next >
Text File  |  1994-05-30  |  22KB  |  541 lines
  1.  Programmer's Guide              
  2.  ~~~~~~~~~~~~~~~~~~
  3.          The ModeDescriptionScript (MDS)
  4.          Use of Constants and FuNctions
  5.          The ModeDescriptionFile (MDF)
  6.          Hints and Tips
  7.  
  8.  
  9.  
  10.  The ModeDescriptionScript (MDS)         
  11.  ===============================
  12.  
  13.         Constant Declarations
  14.         Machine Specifications
  15.         VIDC Registers
  16.         Mode Variables
  17.         Finalisation
  18.  
  19. If you wish to design your own soft-mode you can do so by creating an MDS.
  20. The structure of the MDS must comply with the following rules:
  21.  
  22. 1. The first line of the file must start with the literal text:
  23. 'ModeDescription'. Use the space after it to give a short description of the
  24. mode, and the date you made it.
  25.  
  26. 2. Comments may be included anywhere in the file. A comment must be preceded
  27. by either a ';' or a '|'.
  28.  
  29. 3. The script is sub-divided into 4 sections called lists. Each list is
  30. headed by a card identifying it. Here are the lists:
  31.          * Constant Declaration. You can declare up to 16 constants to be
  32.            used in the script later.
  33.          * Machine Specifications. This is used to specify the monitortype
  34.            for which the mode is suitable and how the VidcEnhancer is to be
  35.            used.
  36.          * VIDC Registers. Here you can define the values to be programmed
  37.            into the VIDC registers.
  38.          * Mode Variables. Here you can specify the values to be programmed
  39.            into the Mode Variables.
  40.  
  41. 4. To use a list you must enter its card at the start of a line. Each
  42. successive line contains the name of a variable followed by an appropriate
  43. value. Variablename and value must be separated by one or more spaces. Edit
  44. the MDS "ExampleMDS" or "DIY_BSDM" to see an example.
  45.  
  46. 5. The last line in the file must start with the literal text: .End
  47.  
  48. Below, each list will be discussed to make its use more clear.
  49.  
  50.  
  51.  
  52.  Constant Declarations (Card: .Declarations)    
  53.  -------------------------------------------
  54.  
  55. This list enables you to declare up to 16 constants (C(0) ~ C(15)). A
  56. constant can be used to make a definition more clear.  <Value> can be
  57. anything that can be passed through BASIC's EVAL function
  58.  
  59. Syntax:
  60.  
  61. C(<VariableNumber>)     <Value>
  62.  
  63. E.g.: You could declare C(0) to hold the number of bits per pixel, C(1)
  64. could hold the number of columns and C(2) the number of rows. You can then
  65. define ScreenSize in the WorkSpaceList as follows:
  66.  
  67.   ScreenSize      C(0)*C(1)*C(2)/8
  68.  
  69.  
  70.  
  71.  Machine Specifications (Card: .MachineSpecs)   
  72.  --------------------------------------------
  73.  
  74. This list lets you define the required machine specifications.
  75.  
  76. Syntax:
  77.  
  78. <Specification>
  79.  
  80.  
  81.  
  82. Specification           Meaning
  83. -----------------------------------------------------------------------------
  84. VidcOn|VidcOff          Turn VidcEnhancer On|Off when this screenmode is
  85.                         selected and Unimode is in 'Auto'-mode.
  86. Standard50Hz            This screenmode can be displayed on a Standard 50Hz
  87.                         monitor
  88. MultiScan               This screenmode can be displayed on a MultiScan
  89.                         monitor
  90. MonoHiRes64Hz           This screenmode can be displayed on a HiRes
  91.                         Monochrome monitor
  92. VGA60Hz                 This screenmode can be displayed on a 60Hz VGA
  93.                         monitor
  94. SVGA                    This screenmode can be displayed on a SVGA
  95.                         monitor (RISC OS 3 only)
  96. LCD                     This screenmode can be displayed on a LCD
  97.                         (RISC OS 3 only)
  98.  
  99.  
  100. E.g.:
  101.  
  102. .MachineSpecs
  103.  
  104.   VidcOn
  105.   MultiScan
  106.   LCD
  107.  
  108. Meaning: This mode is valid only for a MultiScan monitor or LCD display.
  109.          When UniMode is in 'Auto' mode, the VidcEnhancer will be switched
  110.          on.
  111.  
  112.  
  113.  
  114.  VIDC Registers (Card: .VIDCList)       
  115.  --------------------------------
  116.  
  117. You can program each of the VIDC registers defined below. If the
  118. WorkspaceList is present the VIDCList must also be defined. The value with
  119. which you program each register must be EVAL-able by BASIC. If you do not
  120. define a register, its value will be copied from the basemode that you
  121. defined. You must therefore at least define the variable: BaseMode.
  122.  
  123. Syntax:
  124.  
  125. <Registername>          <Value>
  126.  
  127. *** Note, however, that the definition of the registers of a RISC OS 3 mode
  128. is not necessarily identical to the definition of the same mode under
  129. RISC OS 2!! E.g. In RISC OS 2's mode 12 the register HBSR has the value of
  130. 217, while under RISC OS 3 the same register HBSR of mode 12 has the value
  131. 135!
  132.  
  133. Discussed below are the VIDC registers which can be programmed using the
  134. Unimode-package. They're only used by the VIDC. Refer to the !Draw-file:
  135. "VIDC_Regs" to see how the registers, discussed below, are mapped to the
  136. screen. We advise you to print this file if you want to study it. This will
  137. improve the readability of the texts.
  138.  
  139. HCR: Horizontal Cycle Register. This register defines the period of the
  140.      complete horizontal scan, in units of a pixel. It can be programmed
  141.      with values from 2...2048, and must be even.
  142.  
  143.            pixelrate
  144.      HCR = --------- = HBER + HorizontalFrontPorch
  145.            linefreq
  146.  
  147.  
  148. HSWR: Horizontal Sync Width Register. This register defines the width of the
  149.       horizontal sync (HSYNC) pulse, in units of a pixel. It can be
  150.       programmed with values ranging from 2...2048, and must be even.
  151.  
  152.       HSWR = pixelrate * HSYNCDuration
  153.                 [MHz]        [╡s]
  154.  
  155.  
  156. HBSR: Horizontal Border Start Register. This register defines the time from
  157.       the start of the HSYNC-pulse to the start of the border, in
  158.       units of a pixel. It can be programmed with values ranging from
  159.       1...2047, and must be odd.
  160.  
  161.       If no border is demanded, then HBSR should equal HDSR.
  162.  
  163.       HBSR = HSWR + HorizontalBackPorch (?)
  164.  
  165.  
  166. HDSR: Horizontal Display Start Register. This register defines the time from
  167.       the start of the HSYNC-pulse to the start of the active display,
  168.       in units of a pixel. It can be programmed with values ranging from
  169.       1...2047, and must be odd.
  170.  
  171.       HDSR = HBSR + LeftBorderWidth
  172.  
  173.  
  174. HDER: Horizontal Display End Register. This register defines the time from
  175.       the start of the HSYNC-pulse to the end of the active display
  176.       (i.e. the first pixel which is NOT part of the active display), in
  177.       units of a pixel. It can be programmed with values ranging from
  178.       1...2047, and must be odd.
  179.  
  180.       HDER = HDSR + PixelsOnActiveDisplayLine
  181.  
  182.  
  183. HBER: Horizontal Border End Register. This register defines the time from
  184.       the start of the HSYNC-pulse to the end of the border (i.e. the
  185.       first pixel which is NOT part of the border), in units of a pixel. It
  186.       can be programmed with values ranging from 1...2047, and must be odd.
  187.  
  188.       If no border is demanded, then HBER should equal HDER.
  189.  
  190.       HBER = HDER + RightBorderWidth
  191.  
  192.  
  193. HIR: Horizontal Interlace Register. If an interlaced display is required,
  194.      this register should be programmed. In all (most) other cases it may be
  195.      omitted. It can be programmed with values ranging from 1...2047, and
  196.      must be odd.
  197.      *** NOTE: Interlaced displays have never been tested by the authors, so
  198.                we recommend either not to use it OR take very, very much
  199.                time for it (debugging the Unimode-utilities might be
  200.                needed). When using a multiscan monitor, interlaced displays
  201.                should not be used. (Most can't display them anyway.)
  202.  
  203.  
  204. VCR: Vertical Cycle Register. This register defines the period of the
  205.      complete vertical scan, in units of a line. It can be programmed with
  206.      values ranging from 1...1024.
  207.  
  208.              linefreq        pixelrate
  209.      VCR =  ----------- = ----------------- = VBER + VerticalFrontPorch
  210.             rasterfreq    HCR * rasterfreq
  211.  
  212.  
  213. VSWR: Vertical Sync Width Register. This register defines the width of the
  214.       vertical sync (VSYNC) pulse, in units of a line. It can be programmed
  215.       with values ranging from 1...1024.
  216.  
  217.              no. lines during VSYNC
  218.       VSWR = ----------------------
  219.                    linefreq
  220.  
  221.  
  222. VBSR: Vertical Border Start Register. This register defines the time from
  223.       the start of the VSYNC-pulse to the start of the border, in
  224.       units of a line. It can be programmed with values ranging from
  225.       1...1024.
  226.  
  227.       If no border is demanded, then VBSR should equal VDSR
  228.  
  229.       VBSR = VSWR + VerticalBackPorch
  230.  
  231.  
  232. VDSR: Vertical Display Start Register. This register defines the time from
  233.       the start of the VSYNC-pulse to the start of the active display,
  234.       in units of a line. It can be programmed with values ranging from
  235.       1...1024.
  236.  
  237.       VDSR = VBSR + TopBorderHeight
  238.  
  239.  
  240. VDER: Vertical Display End Register. This register defines the time from the
  241.       start of the VSYNC-pulse to the end of the active display (i.e.
  242.       the first line which is NOT part of the active display), in units of a
  243.       line. It can be programmed with values ranging from 1...1024.
  244.  
  245.       VDER = VDSR + ActiveDisplayLines
  246.  
  247.  
  248. VBER: Vertical Border End Register. This register defines the time from the
  249.       start of the VSYNC-pulse to the end of the border (i.e. the
  250.       first line which is NOT part of the active border), in units of a
  251.       line. It can be programmed with values ranging from 1...1024.
  252.  
  253.       If no border is demanded, then VBER should equal VDER.
  254.  
  255.       VBER = VDER + BottomBorderHeight
  256.  
  257.  
  258. CR: Control Register. For this register, a special function has been
  259.     included in the 'UMUserLib'. It can be called with FNCR("..."). Next
  260.     follows a list of keywords that can be used within the quotation-marks,
  261.     and their meaning. Between brackets () is given an abbreviation for that
  262.     keyword. Since the string is decoded by RISC OS' "OS_ReadArgs", all
  263.     keywords must be preceded with a '-'.
  264.  
  265.     * -PixelRate <value>  (-PR). This is the VIDC-pixelrate in MHz, and can
  266.        be set at 8, 12, 16 or 24. When the VidcEnhancer is switched on,
  267.        these rates will be 50% higher. It is NOT possible to set PixelRate
  268.        at e.g. 36. A pixelrate of 36 MHz can be obtained with PixelRate at
  269.        24 and VidcOn in the MachineSpecsList.
  270.  
  271.     * -BitsPerPixel <value>  (-BPP). This is the number of bits per pixel,
  272.        and can be programmed with values 1, 2, 4 or 8 (for resp. 2, 4, 16
  273.        and 256 colour modes).
  274.  
  275.     * -DMARequest <value>  (-DR). This is the moment the VIDC will try to
  276.        get four new words from the main memory. It can be programmed with
  277.        one of the values 0, 1, 2, 3, 4, 5, 6, 7 or 8, where 0 and 4, 1 and
  278.        5, 2 and 6, 3 and 7 have the same meaning (DMA request after resp.
  279.        word 0, 4 etc.). Since it is difficult to give a clear explanation
  280.        of which value should be programmed in which case, a value of 8 asks
  281.        the computer to compute a sensible value and fill it in.
  282.  
  283.     * -InterlaceSync  (-IS). This is a switch. Presence only is important.
  284.        It must only be used if an interlaced display is required. Interlaced
  285.        displays have never been tested by the authors, so we recommend
  286.        either not to use it OR take very, very much time for it (debugging
  287.        the Unimode-utilities might be needed). When using a multiscan
  288.        monitor, interlaced displays should not be used. (Most can't display
  289.        them anyway.)
  290.  
  291.     Examples:
  292.                 CR   FNCR("-PixelRate 16 -BitsPerPixel 4 -DMARequest 8")
  293.                 CR   FNCR("-PR 16 -BPP 4 -DR 8")
  294.  
  295. DATA: It may be desirable to program a VIDC register that has not been
  296.       mentioned above. In such a case you can include "DATA" followed by the
  297.       value you want to write to the VIDC. The value must be 32-bits wide.
  298.       The registeraddress must be contained in the top 6 bits (bits
  299.       26...31). The data to store in the register is contained in bits
  300.       0...23. Bits 24 and 25 must be zero. Theoretically you should not be
  301.       needing this statement. But you never know...
  302.  
  303.       Example:
  304.         In theory, the value to be programmed into the Control Register can
  305.         be defined in three different ways:
  306.  
  307.         1. Via a function
  308.                 CR      FNCR("-PixelRate 8 -BitsPerPixel 4 -DMARequest 2")
  309.  
  310.         2. Via a numerical value
  311.                 CR      59
  312.             or  CR      &3B
  313.             or  CR      %00111011
  314.  
  315.         3. Via a "DATA" statement
  316.                 DATA    &E000003B
  317.  
  318.     NOTE: Remember that this is only an example and you are recommended to
  319.           use option 1. or 2. if the register to be programmed is supported
  320.           by the compiler. "DATA" should only be used as a last resort for
  321.           programming unsupported registers!!
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  Mode Variables (Card: .WorkspaceList)          
  328.  -------------------------------------
  329.  
  330. This list contains the definition of each of the variables that are reported
  331. through OS_ReadModeVariable. If the VIDCList is present the WorkspaceList
  332. must also be defined. The value with which you program each variable must be
  333. EVAL-able. If you do not define a variable, its value will be copied from
  334. the basemode that you defined. You must therefore at least define the
  335. variable BaseMode. These variables are also discussed in the RISC OS 2 PRM
  336. on pages 350...352.
  337.  
  338.  
  339. ModeFlags: For this variable, a special function has been included in the
  340.            'UMUserLib'. It can be called with: FNMF(" ... "). The list of
  341.            keywords that can be used within the quotation-marks, with their
  342.            meaning follows. Between brackets an abbreviation for that
  343.            keyword is given. All keywords act as switches, if they're not
  344.            present they will be automatically UNset. Since the string is
  345.            decoded by RISC OS' "OS_ReadArgs", all keywords must be preceded
  346.            with a '-'.
  347.  
  348.            * -NonGraphicsMode (-NGM). The mode does not support graphics.
  349.               With the current hardware, a mode can always support graphics.
  350.  
  351.            * -TeletextMode (-TM). The mode is a Teletext mode, like mode 7,
  352.               and thus acts a little different with respect to certain
  353.               charactercodes.
  354.  
  355.            * -GapMode (-GM). The mode is a GapMode. This means that a
  356.               character does not use the normal 8 lines, but it uses 10
  357.               instead. This can improve readability of the mode enormously.
  358.  
  359.            * -BBCGapMode (-BBCGM). The mode is a BBC compatible gapmode
  360.               (e.g. mode 3 and 6).
  361.  
  362.            * -HiResMonoMode (-HRMM). The mode is to be displayed on a high
  363.               resolution monochrome monitor.
  364.  
  365.            * -VDUCharsDoubleHeight (-VCDH). VDU characters are displayed in
  366.               double height.
  367.  
  368.            * -HardwareScrollNotUsed (-HSNU). The hardwarescroll available in
  369.               the ARM-based computers will not be used. This can slow down
  370.               your machine enormously, especially when using large modes.
  371.  
  372. ScrRCol: This is the number of characters on a line minus one. If the active
  373.          display is 640 pixels wide (this can be derived from
  374.          [HDER] - [HDSR]), it must be programmed with
  375.          640 / 8 - 1 = 80 - 1 = 79.
  376.  
  377. ScrBRow: This is the number of character-lines minus one. If the active
  378.          display counts 256 lines (this can be derived from
  379.          [VDER] - [VDSR]), it must be programmed with
  380.          256 / 8 - 1 = 32 - 1 = 31. If it is a GapMode, the active display
  381.          might count 250 lines, and ScrBRow should be programmed with
  382.          250 / 10 - 1 = 25 - 1 = 24.
  383.  
  384. NColour: This is the number of colours minus one (1, 3, 15). However 256
  385.          colour modes should be programmed with 64 - 1 = 63. It must conform
  386.          to the CR setting.
  387.  
  388. XEigFactor: This is the number of times an X-coordinate must be divided by 2
  389.             to derive the actual pixel. If there are 640 pixels in the
  390.             active display on a line, and XEigFactor is set to 1, RISC OS
  391.             will work with coordinates in the range from 0 to
  392.             (640 * 2) - 1 = 1279. When set to 2, this range is from 0 to
  393.             (640 * 2 * 2) - 1 = 2559.
  394.  
  395. YEigFactor: This is the number of times a Y-coordinate must be divided by 2
  396.             to derive the actual pixel. If there are 256 lines in the active
  397.             display,  and YEigFactor is set to 1 RISC OS will work with
  398.             coordinates in the range from 0 to (256 * 2) - 1 = 511. When set
  399.             to 2, this range is from 0 to (256 * 2 * 2) -1 = 1023
  400.  
  401. LineLength: This is the number of bytes on a pixel row. It should equal
  402.             (chars per line) * (bits per pixel).
  403.  
  404. ScreenSize: This is the number of bytes one screenbuffer occupies. It
  405.             should equal
  406.             (chars per line) * (bit per pixel) * (active lines).
  407.  
  408. YShftFactor: This variable should not be used. It is kept for compatibility
  409.              reasons only.
  410.  
  411. Log2BPP: This is the ▓log(bits per pixel). This is for 2, 4, 16 and 256
  412.          colour modes resp. 0, 1, 2, 3, and must conform to the CR setting.
  413.  
  414. Log2BPC: This is the ▓log(bytes per character). It usually equals Log2BPP.
  415.  
  416. XWindLimit: This is the number of pixels on an active line, minus 1. So it
  417.             should equal [HDER] - [HDSR] - 1.
  418.  
  419. YWindLimit: This is the number of active lines, minus 1. So it should equal
  420.             [VDER] - [VDSR] - 1.
  421.  
  422.  
  423. Syntax:
  424.  
  425. <Variablename>          <Value>
  426.  
  427.  
  428.  
  429.  Finalisation (Card: .End)              
  430.  -------------------------
  431.  
  432. This card is used to signal the end of the definition. Anything beyond this
  433. card is ignored.
  434.  
  435.  
  436.  
  437.  Use of Constants and FuNctions         
  438.  ==============================
  439.  
  440. The value programmed into either a VIDCRegister or a ModeVariable can be
  441. virtually anything. Of course you can program it with a normal integer. But,
  442. you can also pass a formula like: 480*256*4. Or if you have declared a
  443. constant something like:  C(0)*C(1)*C(2). But that's not where it ends. You
  444. can make it even more complex. For instance: LOG(C(2))/LOG(2) to calculate
  445. Log2BPP. This can be done because the value is passed through the function
  446. EVAL before it is programmed into the MDF. The great advantage of this
  447. mechanism is the fact that FuNctions can be part of the value. For this
  448. purpose the library 'UMUserLib' is linked into the compiler. Currently the
  449. following FuNctions are provided by this library:
  450.  
  451. FNCR()
  452. Instead of thumbing through the Functional Description in the VIDC
  453. Datasheets and manually working out the contents of the Control Register,
  454. you can simply use this function to calculate the correct value for you.
  455. Refer to the paragraph 'VIDC Registers' for a description of this function.
  456.  
  457. FNMF()
  458. The variable ModeFlags is a compound variable. Each bit has a different
  459. meaning. By using this function you needn't calculate the contents of this
  460. variable yourself. Refer to the paragraph 'Mode Variables' for a description
  461. of this function.
  462.  
  463. FN_DecodeCR
  464. This function reverses the effect of FNCR() and is used by
  465. 'Expand(All)' when creating an MDS.
  466.  
  467. FN_DecodeMF
  468. This function reverses the effect of FNMF() and is used by 'Expand(All)'
  469. when creating an MDS.
  470.  
  471. You can of course add other functions to your personal copy of the library to
  472. enhance the package to your own personal needs. If you do, however, we would
  473. like to hear from you, as we may want to include these enhancements in
  474. future releases of the package.
  475.  
  476. The MDS's "ExampleMDS" and "DIY_BSDM" are working examples of how you can
  477. create your own MDS.
  478.  
  479.  
  480.  
  481. The ModeDescriptionFile (MDF)           
  482. =============================
  483.  
  484. In order to use a ModeDescriptionScript (MDS) you need to compile it into a
  485. ModeDescriptionFile (MDF). Refer to the paragraphs "!UniMode" and
  486. "CompileMDS" for an explanation about how this can be done.
  487.  
  488. The MDF can be loaded into the memory with the command *ModeLoad from the
  489. CLI. It can also be loaded via the desktop front-end "!UniMode". Refer to
  490. the appropriate paragraph for more details on this.
  491.  
  492. The MDF is a binary file with the filetype &103 ("UniMode"). The structure
  493. of this file is as follows.
  494.  
  495. Offset into File        Contents
  496. -----------------------------------------------------------------------
  497.  
  498. &00000000               MachineSpecs word
  499.  
  500. &00000004               Offset to the VIDC list from the beginning of the
  501.                         file (If bit30 of the MachineSpecs word is set)
  502.  
  503. &00000008               Offset to WorkSpaceList from the beginning of the
  504.                         file (If bit30 of the MachineSpecs word is set)
  505.  
  506. [&00000004]             VIDC list (format of the list as defined on page 708
  507.                         of the RISC OS 2 PRM)
  508.         +0      0       (indicates format of list)
  509.         +4      VIDC basemode
  510.         :
  511.         +n      -1      (n equals: [&00000008]-4)
  512.  
  513. [&00000008]             Workspace list (format of the list as defined on
  514.                         page 709 of the RISC OS 2 PRM)
  515.         +0      0       (indicates format of list)
  516.         +4      Basemode
  517.         :
  518.         +n      -1
  519.  
  520.  
  521. The bits of the MachineSpecs word have the following meaning
  522.  
  523. bit     meaning if set
  524. ---------------------------------------------------------------------
  525.  
  526. 0..n    MonitorType n is supported by this mode.
  527.         b0 = Standard 50Hz monitor
  528.         b1 = MultiScan monitor
  529.         b2 = Mono HiRes 64Hz monitor
  530.         b3 = VGA 60Hz monitor
  531.         b4 = SVGA monitor (RISC OS 3 only)
  532.         b5 = LCD display (RISC OS 3 only)
  533.  
  534. 30      VIDClist & WorkSpaceList are included
  535.  
  536. 31      VidcEnhancer should be switched on
  537.  
  538. On the whole you will find that the only MDF's that do NOT have bit30 of the
  539. MachineSpecs word set are "VidcOn" and "VidcOff".
  540.  
  541.